<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<!--
 * Build.html
 *
 * Instructions for building Version Information Editor.
 *
 * $Rev: 137 $
 * $Date: 2011-03-28 01:39:24 +0000 (Mon, 28 Mar 2011) $
 *
 * ***** BEGIN LICENSE BLOCK *****
 *
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with the
 * License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The Original Code is Build.html
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2011 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributors:
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
-->

<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

<head>
  <title>
    Building Version Information Editor
  </title>
  <style type="text/css">
    body {
      font-family: Verdana, Arial, sans-serif;
    }
    pre, code {
      font-family: "Lucida Console", "Courier New", Courier, mono;
    }
    dl.spaced dt {
      margin-top: 0.5em;
    }
    h1 {
      text-align: center;
    }
    h2 {
      padding-bottom: 0.25em;
      border-bottom: 1px silver solid;
    }
    .indent {
      margin-left: 2em;
    }
    ul.spaced li,
    ol.spaced li {
      margin-top: 0.5em;
    }
    .prompt {
      color: blue;
      font-weight: bold;
    }
    .note {
      padding: 0.5em;
      border: 1px silver dotted;
    }
  </style>
</head>

<body>

<h1>
  Version Information Editor Build Instructions
</h1>

<h2>
  Introduction
</h2>

<p>
  <em>Version Information Editor</em> is written in Object Pascal and is
  targeted at Delphi 2010. The Delphi IDE can be used to modify the source and
  to perform test builds. Final builds should be built using the provided
  makefile, but you can get away with using the IDE if you don't change any
  resources.
</p>

<h2>
  Dependencies
</h2>

<p>
  Several DelphiDabbler libraries and components are required in to compile
  <em>Version Information Editor</em>. They are:
</p>

<ul class="spaced">
  <li>
    <a
      href="http://www.delphidabbler.com/software/verinfo"
    >Version Information Component</a> v3.3 or later.
  </li>
  <li>
    <a
      href="http://www.delphidabbler.com/software/aboutbox"
    >About Box Component</a> v3.5.1 or later.
  </li>
  <li>
    <a
      href="http://www.delphidabbler.com/software/dropfiles"
    >Drop Files Components</a> v5.0.2 or later.
  </li>
  <li>
    <a
      href="http://www.delphidabbler.com/software/wdwstate"
    >Window State Components</a> v5.3.1 or later.
  </li>
  <li>
    <a
      href="http://www.delphidabbler.com/software/shellfolders"
    >Shell Folders Unit</a> v2.3 or later.
  </li>
</ul>

<p>
  These components must be installed into the Delphi component palette since
  they are required at design time. 
</p>

<p>
  All the components and classes must be installed in the same directory, so
  the easiest thing to do is to install everything into the Delphi user design
  time package. <a
    href="http://www.delphidabbler.com/url/install-comp"
  >See here</a> if you need help doing this.
</p>

<h2>
  Build Tools
</h2>

<p>
  The following tools are required to build <em>VIEd</em>.
</p>

<h3>
  Delphi
</h3>

<p>
  A copy of the Delphi 2010 command line compiler is required to build the
  object Pascal code from the provided makefile.
</p>

<p>
  You can use the Delphi IDE to edit the code and test compile it, but final
  builds should be created using the makefile, which requires the following
  tools that are supplied with Delphi: 
</p>

<p>
  The following command line tools are required to compile the whole project
  using the build scripts.
</p>

<dl class="spaced">
  <dt>
    <code>DCC32</code>
  </dt>
  <dd>
    The Delphi command line compiler.
  </dd>
  
  <dt>
    <code>BRCC32</code>
  </dt>
  <dd>
    The Borland resource compiler. This is used to compile resource source
    (<code>.rc</code>) files.
  </dd>
</dl>

<p>
  The following environment variables are associated with these tools:
</p>

<dl>
  <dt class="spaced">
    <code>DELPHIROOT</code> - required unless <code>DELPHI2010</code> is set.
  </dt>
  <dd>
    Should be set to the install directory of the version of Delphi being
    used. <code>DCC32</code> and <code>BRCC32</code> are expected to be in the
    <code>Bin</code> sub-directory of <code>DELPHIROOT</code>.
  </dd>

  <dt class="spaced">
    <code>DELPHI2010</code> - optional
  </dt>
  <dd>
    This environment variable can be set to the Delphi 2010 install directory.
    When <code>DELPHI2010</code> is defined <code>DELPHIROOT</code> will be set
    to the value of <code>DELPHI2010</code>.
  </dd>
</dl>

<h3>
  Borland Make
</h3>

<p>
  This is the make tool that ships with Delphi. You can use any version that
  works.
</p>

<h3>
  DelphiDabbler Version Information Editor
</h3>

<p>
  Yes, you need an executable version of the tool you are going to build. Use an
  existing stable version from v2.11.2. This tool is used to compile version
  the program's version information (<code>.vi</code>) files into intermediate
  resource source (<code>.rc</code>) files. You can get the latest stable
  version from
  <a
    href="http://www.delphidabbler.com/software/vied"
  >http://www.delphidabbler.com/software/vied</a>.
</p>

<h3>
  Inno Setup
</h3>

<p>
  The Unicode version on the Inno setup command line compiler is needed to
  create <em>CodeSnip</em>'s install program. v5.4.0 (u) or later is required as
  is a compatible version of the ISPP pre-processor. You can get Inno Setup with
  ISPP at <a
    href="http://www.jrsoftware.org/isinfo.php"
  >http://www.jrsoftware.org/isinfo.php</a>. Choose the Unicode version. If you
  already have the ANSI version the Unicode version can be installed alongside
  it - just use a different install directory and program group name.
</p>

<p>
  The compiler is expected to be on the path unless its install directory is
  specified by the <code>INNOSETUP</code> environment variable.
</p>

<h3>
  Microsoft HTML Help Compiler (HHC)
</h3>

<p>
  This command line compiler is supplied with Microsoft HTML Help Workshop. It
  is used to compile the <em>VIEd</em> help file.
</p>

<p>
  The program is expected to be on the path unless its install directory is
  specified by the <code>HHCROOT</code> environment variable.
</p>

<h3>
  Zip
</h3>

<p>
  This program is used to create <em>VIEd</em>'s release file. You can get a
  Windows command line version at
  <a
    href="http://stahlforce.com/dev/index.php?tool=zipunzip"
  >http://stahlforce.com/dev/index.php?tool=zipunzip</a>.
</p>

<p>
  The program is expected to be on the path unless its install directory is
  specified by the <code>ZIPROOT</code> environment variable.
</p>

<h2>
  Preparation
</h2>

<h3>
  Get the Source Code
</h3>

<p>
  First you need to get the source code of <em>Version Information Editor</em>.
  There are two choices:
</p>

<ol class="spaced">
  <li>
    Download the source code of the latest release from the <a
      href="http://www.delphidabbler.com/software/vied/download"
    >Version Information Editor Download Page</a>. Unzip the download into a 
    suitable folder, preserving the directory structure.
  </li>
  <li>
    <div>
      Get the source code of a suitable release or the latest development
      code using <em>Subversion</em>. Check out the latest development
      code into a folder named <code>vied</code> by doing:
    </div>
    <pre class="indent"><span class="prompt">&gt;</span> svn checkoput http://verinfo-tools.googlecode.com/svn/trunk/vied/ vied</pre>
    <div>
      Alternatively check out the source code of a release by doing
    </div>
    <pre class="indent"><span class="prompt">&gt;</span> svn checkout http://verinfo-tools.googlecode.com/svn/tags/vied/release-9.9.9/ vied</pre>
    <div>
      Replace <code>9.9.9</code> with the version number of the required
      release. All available releases can be viewed in <a
        href="http://code.google.com/p/verinfo-tools/source/browse/#svn/tags/vied"
      >this branch</a> of the SVN repository.
    </div>
  </li>
</ol>

<h3>
  Configure the Environment
</h3>

<p>
  The makefile requires that the following environment variables are set:
</p>

<dl class="spaced">
  <dt>
    <code>DELPHIROOT</code> or <code>DELPHI2010</code>
  </dt>
  <dd>
    <code>DELPHIROOT</code> must be set to the install directory of the version
    of Delphi being used. If you are using Delphi 2010 you can set
    <code>DELPHI2010</code> to its install directory. If set
    <code>DELPHI2010</code> will be used in preference to
    <code>DELPHIROOT</code>.
  </dd>
  <dt>
    <code>DELPHIDABLIB</code> or <code>DELPHIDABLIBD2010</code>
  </dt>
  <dd>
    <code>DELPHIDABLIB</code> must be set to the directory where the required
    DelphiDabbler components and library files are installed in the version of
    Delphi to be used. If you are using Delphi 2010 you can set
    <code>DELPHIDABLIBD2010<code> instead and it will be used is preference.
  </dd>
  <dt>
    <code>INNOSETUP</code>
  </dt>
  <dd>
    Set to the install directory of Inno Setup 5. If not set Inno Setup must be
    on the system path.
  </dd>
  <dt>
    <code>VIEDROOT</code>
  </dt>
  <dd>
    Set to the path where the DelphiDabbler Version Information Editor (VIEd) is 
    installed. If not set VIEd must be on the system path.
  </dd>
  <dt>
    <code>HHCROOT</code>
  </dt>
  <dd>
    Set to the path where the Microsoft HTML Help Compiler is installed. If not
    set the compiler must be on the system path.
  </dd>
  <dt>
    <code>ZIPROOT</code>
  </dt>
  <dd>
    Set to the path where Zip.exe is installed. If not set Zip.exe must be on
    the system path.
  </dd>
  <dt>
    <code>RELEASEFILENAME</code>
  </dt>
  <dd>
    Set to the name of the zip file to be used to store a release. This file
    name should have no path or extension. If not set then &quot;dd-vied&quot;
    is used.
  </dd>
</dl>

<p>
  You may find it convenient to create a batch file that sets up the environment
  that you run from a command window before running the makefile.
</p>

<h3>
  Configure the Source Tree
</h3>

<p>
  After checking out or downloading and extracting the source code you should
  have the following directory structure:
</p>

<pre>./
  |
  +-- Docs                   - documentation
  |
  +-- Source                 - main source code
      |
      +-- Assets             - assets to be included in resources
      |
      +-- Help               - source for help file: contains project files
          |
          +-- CSS            - style sheet used for help file
          |
          +-- HTML           - HTML help topic files</pre>  

<p>
  If your source tree also contains one or more of the <code>Bin</code>,
  <code>Exe</code> or <code>Release</code> directories that's OK, as will become 
  clear later. Subversion users will also see the usual hidden <code>.svn</code>
  directories.
</p>

<p>
  The first thing to do before attempting to hack the code is to configure the
  source tree. Open a console window and navigate to the <code>Source</code>
  directory. Run any script you have created to set the environment variables
  then do:
</p>

<pre class="indent"><span class="prompt">&gt;</span> make config</pre>

<p>
  This script does two things:
</p>

<ol class="spaced">
  <li>
    It creates the <code>Bin</code>, <code>Exe</code> and
    <code>Release</code> directories, along with various sub-directories of
    <code>Bin</code> that are required to receive the binary code. If any of
    these directories already existed they will have been emptied.
  </li>
  <li>
    It creates the <code>.cfg</code> file from a template file. This file is
    required to configure the Delphi command line compiler. The 
    <code>.cfg</code> file will be ignored by Subversion.
  </li>
</ol>

<p>
  If you intending to edit and compile the code using the Delphi IDE you must
  also run the following command from the <code>Source</code> directory:
</p>

<pre class="indent"><span class="prompt">&gt;</span> make resources</pre>

<p>
  This creates the resource files that the IDE needs to link into compiled
  executables.
</p>

<p>
  You are now ready to modify the code if you wish and to build the source.
</p>

<h2>
  Building Version Information Editor
</h2>

<p>
  The code is built using the makefile, which must be run from a command line
  that is set to the <code>Source</code> directory. Run any script you have
  created once, before using the makefile for the first time.
</p>

<p>
  The makefile offers several options. They are:
</p>

<dl class="spaced">
  <dt>
    <code>make config</code>
  </dt>
  <dd>
    As we have already seen this command configures the source tree. It should
    be run before using any other command. The command creates the required
    Delphi <code>.cfg</code> file from its template and creates empty
    <code>Bin</code>, <code>Exe</code> and <code>Release</code> directories.
  </dd>
  
  <dt>
    <code>make resources</code>
  </dt>
  <dd>
    Compiles the resource files required to build the program. Files are placed
    in the <code>Bin</code> directory, which must exist.
  </dd>

  <dt>
    <code>make pascal</code>
  </dt>
  <dd>
    Compiles the pascal source using the required version of Delphi. Requires
    that resource files are present in the <code>Bin</code> directory. The
    compiled exe file is placed in the <code>Exe</code> directory.
  </dd>
  
  <dt>
    <code>make vied</code>
  </dt>
  <dd>
    Compiles <em>VIEd</em> from source. This command is equivalent to <code>make
    resources</code> followed by <code>make pascal</code>.
  </dd>
  
  <dt>
    <code>make help</code>
  </dt>
  <dd>
    Compiles the HTML help file from source. The compiled file is placed in the
    <code>Exe</code> directory.
  </dd>
  
  <dt>
    <code>make setup</code>
  </dt>
  <dd>
    Builds the setup program. The command requires that the <em>VIEd</em>
    executable and the help file have been compiled and are present in the
    <code>Exe</code> directory. It also requires that certain documents are
    present in the <code>Docs</code> directory. The compiled setup program is
    placed in the <code>Exe</code> directory.
  </dd>
  
  <dt>
    <code>make release</code>
  </dt>
  <dd>
    Creates a zip file containing the required release files. By default the
    release file is named <code>dd-vied.zip</code> but this can be changed by
    setting the <code>RELEASEFILENAME</code> environment variable (see above).
  </dd>

  <dt>
    <code>make everything</code> or <code>make</code>
  </dt>
  <dd>
    This is the default option used when make is run with no targets. It
    configures the source tree, builds the <em>VIEd</em> executable and the help
    file, then builds the install program and finally creates the release zip
    file.
  </dd>
  
  <dt>
    <code>make clean</code>
  </dt>
  <dd>
    Deletes unwanted and temporary files and directories from the source tree. 
    The command does not delete the <code>Bin</code>, <code>Exe</code> and
    <code>Release</code> directories and contents and neither does it delete the
    <code>.cfg</code> from the <code>Source</code> directory.
  </dd>
  
  <dt>
    <code>make deepclean</code>
  </dt>
  <dd>
    Like <code>make clean</code> this command deletes unwanted and temporary
    files and directories. It also removes the directories and files created by
    <code>make config</code>, i.e. the <code>Bin</code>, <code>Exe</code> and
    <code>Release</code> directories along with the  <code>.cfg</code> in the
    <code>Source</code> directory.
  </dd>
</dl>

<p class="note">
  <strong>Note:</strong> If the <code>make</code> command fails to run you may
  need to use <code>%DELPHIROOT%\Bin\Make</code> or
  <code>%DELPHI2010%\Bin\Make</code> depending on which environment variable you
  have set.
</p>

<h2>
  Copyright
</h2>

<p>
  If you are planning to re-use or modify any of the code, please see
  <code>SourceCodeLicenses.txt</code> in the <code>Docs</code> directory for
  an overview of the various open source licenses that apply to the
  <em>Version Information Editor</em> source code.
</p>

</body>

</html>